/*
 * Copyright (c) 2012-2017 Red Hat, Inc.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *   Red Hat, Inc. - initial API and implementation
 */
package org.eclipse.che.api.machine.server.spi;

import java.util.Collection;
import java.util.List;
import org.eclipse.che.api.core.NotFoundException;
import org.eclipse.che.api.machine.server.exception.SnapshotException;
import org.eclipse.che.api.machine.server.model.impl.SnapshotImpl;

/**
 * Stores metadata of snapshots
 *
 * @author andrew00x
 * @author Yevhenii Voevodin
 */
public interface SnapshotDao {

  /**
   * Retrieves snapshot metadata by machine related information.
   *
   * @param workspaceId workspace id
   * @param envName name of environment
   * @param machineName name of machine
   * @return snapshot which matches given parameters
   * @throws NotFoundException when snapshot with such workspaceId, envName and machineName doesn't
   *     exist
   * @throws SnapshotException when any other error occurs
   */
  SnapshotImpl getSnapshot(String workspaceId, String envName, String machineName)
      throws NotFoundException, SnapshotException;

  /**
   * Retrieve snapshot metadata by id
   *
   * @param snapshotId id of required snapshot
   * @return {@link SnapshotImpl} with specified id
   * @throws NotFoundException if snapshot with specified id not found
   * @throws SnapshotException if other error occurs
   */
  SnapshotImpl getSnapshot(String snapshotId) throws NotFoundException, SnapshotException;

  /**
   * Save snapshot metadata
   *
   * @param snapshot snapshot metadata to store
   * @throws SnapshotException if error occurs
   */
  void saveSnapshot(SnapshotImpl snapshot) throws SnapshotException;

  /**
   * Find snapshots by workspace.
   *
   * @param workspaceId workspace specified in desired snapshot
   * @return list of snapshot that satisfy provided queries, or empty list if no desired snapshots
   *     found
   * @throws SnapshotException if error occurs
   */
  List<SnapshotImpl> findSnapshots(String workspaceId) throws SnapshotException;

  /**
   * Remove snapshot by id
   *
   * @param snapshotId id of snapshot that should be removed
   * @throws NotFoundException if snapshot with specified id not found
   * @throws SnapshotException if other error occur
   */
  void removeSnapshot(String snapshotId) throws NotFoundException, SnapshotException;

  /**
   * Replaces all the existing snapshots related to the given workspace with a new list of
   * snapshots.
   *
   * @param workspaceId the id of the workspace to replace snapshots
   * @param envName the name of the environment in workspace with given id which is used to search
   *     those snapshots that should be replaced
   * @param newSnapshots the list of the snapshots which will be stored instead of existing ones
   * @return the list of replaced(removed/old) snapshots for given workspace and environment, or an
   *     empty list when there is no a single snapshot for the given workspace
   * @throws SnapshotException when any error occurs
   */
  List<SnapshotImpl> replaceSnapshots(
      String workspaceId, String envName, Collection<? extends SnapshotImpl> newSnapshots)
      throws SnapshotException;
}
